using System;

namespace Sedna.Core.Persistence
{
	/// <summary>
	/// this is a base interface for those Filter states that
	/// are used to generate an instance of a ICriteria automatically
	/// 
	/// The only responsibility of a developer while creating such a filter
	/// is to provide appropriate class properties that corresponds the
	/// target PersistentType entity class.
	/// 
	/// To mark up those properties significant for ICriteria generation 
	/// <see cref="FilterPropertyAttribute"/> shall be used for each property
	/// that represents a filter state
	/// 
	/// This filter state is used by <see cref="AttributeBasedFilterCriteriaBuilder"/>
	/// </summary>
	public interface IExternalCriteriaFilterState : IFilterState
	{
		/// <summary>
		/// type of a persistent entity this filter is applicable for
		/// 
		/// As it is clear from this interface, this filter state can be used with 
		/// queries that are made against one persistent entity only (thus single <c>PersistentType</c> property).
		/// 
		/// This is a preferrable way to make selections and queries, since this approach reduced the amount of 
		/// custom code dramatically. However, there are many situations, especialy on the "query-like" screens
		/// where a single entity is not enough either to populate a screen or to build a request criteria.
		/// 
		/// To overcome this, one can create an SQL VIEW and map a surrogate entity upon it 
		/// (although issues with a 1st and especially A 2dn level caching) must be addressed (i.e. such a surrogate entity
		/// must never be cached, lest the screen display stale data; the reason for this is that NHibernate consideres
		/// such entities as independent ones, mapped to separate tables, thus it will NOT invalidate or update its caches).
		/// 
		/// However, even using a surrogate entity might not be enough, in this case one might use the <see cref="ICriteriaFilterState"/>
		/// or even <see cref="IHqlFilterState"/>. The latter allows a developer to create sophisticated HQL queries
		/// based upon internal filter state.
		/// </summary>
		Type PersistentType
		{
			get;
		}
	}
}
